Configuration Reference

Complete reference for all configuration options available in the Conviso Flutter SDK.

OpenCDPConfig

The main configuration object passed to OpenCDPSDK.initialize().

Option	Type	Required	Description
cdpApiKey	String	Yes	Your API key for Conviso
cdpRequestTimeout	Duration	No	How long to wait for one gateway host, in seconds via Duration. Default: 30 seconds. Values outside 5–120 seconds are clamped to that range.
debug	bool	No	Enables verbose debug logging. Default: false
iOSAppGroup	String	Yes (iOS Push)	The App Group ID for iOS push tracking (e.g., group.com.yourcompany.yourapp)
autoTrackScreens	bool	No	If true, automatically tracks screen views via NavigatorObserver. Default: false
trackApplicationLifecycleEvents	bool	No	If true, tracks app lifecycle events (opened, backgrounded, etc.). Default: false
autoTrackDeviceAttributes	bool	No	If true, automatically tracks device attributes (OS, version, model). Default: false
sendToCustomerIo	bool	No	If true, enables dual-write to Customer.io. Default: false
customerIo	CustomerIOConfig	Conditional	Configuration object for Customer.io. Required if sendToCustomerIo is true
enableInAppMessages	bool	No	Conviso native in-app: when true, starts CDPInAppManager (SSE + /sync). Default: false. See In-app messaging (Flutter).
enableInAppRealtime	bool	No	When true (default), opens the SSE stream while enableInAppMessages is true.
inAppPollInterval	Duration	No	Polling fallback when SSE is off or disconnected. Default: 30s.
inAppRealtimeStaleTimeout	Duration	No	Max silence on SSE before reconnect. Default: 60s.
inAppRealtimeMaxBackoff	Duration	No	Max backoff between SSE reconnect attempts. Default: 30s.
inAppSyncLimit	int	No	Max messages per /sync (1–50). Default: 10.
inAppPlatformOverride	String?	No	Optional platform query override for in-app APIs.
inAppAppVersionOverride	String?	No	Optional app_version sent on sync / impression.

Example

OpenCDPConfig(
  // Required
  cdpApiKey: 'your-cdp-api-key',
  
  // iOS Push (Required for iOS push notifications)
  iOSAppGroup: 'group.com.yourcompany.yourapp',
  
  // Debug
  debug: true,
  
  // Feature Toggles
  autoTrackScreens: true,
  trackApplicationLifecycleEvents: true,
  autoTrackDeviceAttributes: true,
  
  // Customer.io
  sendToCustomerIo: true,
  customerIo: CustomerIOConfig(
    // ... see below
  ),
)

Gateway request timeout

cdpRequestTimeout is a Duration. Set it in seconds. The built-in default is 30 seconds. The SDK clamps any value below 5 seconds up to 5 seconds, and any value above 120 seconds down to 120 seconds.

The timeout is how long the SDK waits for one gateway host to answer a single request. On a timeout, a network error, or a non-success status, the SDK tries the next host immediately:

1. https://api.opencdp.io/gateway/data-gateway
2. https://api.open-cdp.com/gateway/data-gateway
3. https://api.open-cdp.xyz/gateway/data-gateway

Leave cdpRequestTimeout unset to keep the 30 second default. To wait 20 seconds on each host:

OpenCDPConfig(
  cdpApiKey: 'your-cdp-api-key',
  cdpRequestTimeout: const Duration(seconds: 20),
)

CustomerIOConfig

Configuration for Customer.io integration when dual-write is enabled.

Option	Type	Required	Description
siteId	String	Yes	Your Customer.io Site ID
apiKey	String	Yes	Your Customer.io API Key
region	Region	Yes	Customer.io region (Region.us or Region.eu)
autoTrackDeviceAttributes	bool	No	If true, tracks device attributes in Customer.io. Default: false
migrationSiteId	String	No	Migration site ID for Customer.io
inAppConfig	InAppConfig?	No	Customer.io only: CIO in-app when dual-writing. Not Conviso Data Gateway in-app — use enableInAppMessages on OpenCDPConfig instead. See Flutter in-app guide.
pushConfig	CustomerIOPushConfig	No	Push notification configuration

Example

CustomerIOConfig(
  // Required
  siteId: 'your-site-id',
  apiKey: 'your-customer-io-api-key',
  region: Region.us,
  
  // Optional
  autoTrackDeviceAttributes: true,
  migrationSiteId: 'your-migration-site-id',
  
  // Advanced configurations
  inAppConfig: InAppConfig(
    siteId: 'your-site-id',
  ),
  pushConfig: CustomerIOPushConfig(
    // ... push notification config
  ),
)

Region Enum

Specifies the Customer.io data center region.

enum Region {
  us,  // United States
  eu,  // European Union
}

Complete Configuration Example

Here's a complete example with all common options:

await OpenCDPSDK.initialize(
  config: OpenCDPConfig(
    // === Core Configuration ===
    cdpApiKey: 'your-cdp-api-key',
    debug: true, // Set to false in production
    
    // === iOS Push Notification Support ===
    iOSAppGroup: 'group.com.yourcompany.yourapp',
    
    // === Automatic Tracking Features ===
    autoTrackScreens: true,
    trackApplicationLifecycleEvents: true,
    autoTrackDeviceAttributes: true,

    // === Conviso native in-app (Data Gateway) ===
    enableInAppMessages: true,
    enableInAppRealtime: true,

    // === Customer.io Integration ===
    sendToCustomerIo: true,
    customerIo: CustomerIOConfig(
      // Required
      siteId: 'your-site-id',
      apiKey: 'your-customer-io-api-key',
      region: Region.us,
      
      // Optional
      autoTrackDeviceAttributes: true,
      migrationSiteId: 'your-migration-site-id',
      
      // Push Configuration
      pushConfig: CustomerIOPushConfig(
        pushConfigAndroid: CustomerIOPushConfigAndroid(
          pushClickBehavior: PushClickBehaviorAndroid.activityPreventRestart,
        ),
      ),
      
      // In-app (Customer.io SDK — not Conviso native; see enableInAppMessages above)
      inAppConfig: InAppConfig(
        siteId: 'your-site-id',
      ),
    ),
  ),
);

Environment-Specific Configuration

It's recommended to use different configurations for different environments:

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Determine environment
  const String environment = String.fromEnvironment(
    'ENVIRONMENT',
    defaultValue: 'development',
  );
  
  // Configure based on environment
  await OpenCDPSDK.initialize(
    config: OpenCDPConfig(
      cdpApiKey: environment == 'production'
          ? 'your-production-api-key'
          : 'your-development-api-key',
      debug: environment != 'production',
      autoTrackScreens: true,
      trackApplicationLifecycleEvents: true,
      autoTrackDeviceAttributes: true,
      iOSAppGroup: 'group.com.yourcompany.yourapp',
    ),
  );
  
  runApp(MyApp());
}

Best Practices

1. Never Commit API Keys

Store API keys securely and never commit them to version control:

// ✅ Good - Use environment variables
const cdpApiKey = String.fromEnvironment('CDP_API_KEY');

// ❌ Bad - Hardcoded key
const cdpApiKey = 'sk_live_abc123...'; // Never do this!

2. Disable Debug Logging in Production

OpenCDPConfig(
  debug: kDebugMode, // Automatically false in release builds
  // ... other config
)

3. Use Consistent App Group IDs

The iOS App Group ID must be:

• Identical between your Dart code and Xcode configuration
• Unique to your organization
• In the format: group.com.yourcompany.yourapp

Related

• Quick Start Guide
• Screen Tracking Setup
• Push Notifications Setup
• In-app messaging (Flutter / Data Gateway)